The _p_m_V_a_l_u_e structure is embedded within the _p_m_R_e_s_u_l_t structure that is
used to return one or more performance metrics; see ppppmmmmFFFFeeeettttcccchhhh(3).
All performance metric values may be encoded in a _p_m_A_t_o_m_V_a_l_u_e union,
defined as follows;
typedef union {
__int32_t l; /* 32-bit signed */
__uint32_t ul; /* 32-bit unsigned */
__int64_t ll; /* 64-bit signed */
__uint64_t ull; /* 64-bit unsigned */
float f; /* 32-bit floating point */
double d; /* 64-bit floating point */
char *cp; /* char ptr */
void *vp; /* void ptr */
} pmAtomValue;
The routine ppppmmmmEEEExxxxttttrrrraaaaccccttttVVVVaaaalllluuuueeee provides a convenient mechanism for extracting
values from the _p_m_V_a_l_u_e part of a _p_m_R_e_s_u_l_t structure, optionally
converting the data type, and making the result available to the
application programmer.
_i_t_y_p_e defines the data type of the input value held in _i_v_a_l according to
the storage format defined by _v_a_l_f_m_t (see ppppmmmmFFFFeeeettttcccchhhh(3)). _o_t_y_p_e defines the
data type of the result to be placed in _o_v_a_l.
The value for _i_t_y_p_e is typically extracted from a _p_m_D_e_s_c structure,
following a call to ppppmmmmLLLLooooooookkkkuuuuppppDDDDeeeesssscccc(3) for a particular performance metric.
The _o_t_y_p_e value should be one of the defined PPPPMMMM____TTTTYYYYPPPPEEEE____... values, that
have a 1:1 correspondence with the fields in the _p_m_A_t_o_m_V_a_l_u_e union.
Normally the _v_a_l_f_m_t parameter would be plucked from the same _p_m_R_e_s_u_l_t
structure that provides the _i_v_a_l parameter, and if _v_a_l_f_m_t specifies
PPPPMMMM____VVVVAAAALLLL____IIIINNNNSSSSIIIITTTTUUUU, then the following types are not allowed, as these cannot
be encoded in 32-bits; ________iiiinnnntttt66664444____tttt, ________uuuuiiiinnnntttt66664444____tttt, ddddoooouuuubbbblllleeee, cccchhhhaaaarrrr **** and vvvvooooiiiidddd ****
(the corresponding _i_t_y_p_e values are PPPPMMMM____TTTTYYYYPPPPEEEE____66664444, PPPPMMMM____TTTTYYYYPPPPEEEE____UUUU66664444,
PPPPMMMM____TTTTYYYYPPPPEEEE____DDDDOOOOUUUUBBBBLLLLEEEE, PPPPMMMM____TTTTYYYYPPPPEEEE____SSSSTTTTRRRRIIIINNNNGGGG and PPPPMMMM____TTTTYYYYPPPPEEEE____AAAAGGGGGGGGRRRREEEEGGGGAAAATTTTEEEE respectively). If
_v_a_l_f_m_t specifies PPPPMMMM____VVVVAAAALLLL____PPPPTTTTRRRR, then the value will be extracted from the
associated _p_m_V_a_l_u_e_B_l_o_c_k structure, and the ________iiiinnnntttt33332222____tttt, ________uuuuiiiinnnntttt33332222____tttt and
ffffllllooooaaaatttt options (_i_t_y_p_e being PPPPMMMM____TTTTYYYYPPPPEEEE____33332222, PPPPMMMM____TTTTYYYYPPPPEEEE____UUUU33332222 and PPPPMMMM____TTTTYYYYPPPPEEEE____FFFFLLLLOOOOAAAATTTT
respectively) are not allowed, as PPPPMMMM____VVVVAAAALLLL____IIIINNNNSSSSIIIITTTTUUUU is the appropriate
encoding for these.
The following table defines the various possibilities for the type
conversion -- the input type (_i_t_y_p_e) is shown vertically, and the output
type (_o_t_y_p_e) is shown horizontally. Y means the conversion is always
acceptable, N means the conversion can never be performed (the function
returns PPPPMMMM____EEEERRRRRRRR____CCCCOOOONNNNVVVV), P means the conversion may lose accuracy (but no
error status is returned), T means the result may be subject to high-
order truncation (in which case the function returns PPPPMMMM____EEEERRRRRRRR____TTTTRRRRUUUUNNNNCCCC) and S
means the conversion may be impossible due to the sign of the input value
(in which case the function returns PPPPMMMM____EEEERRRRRRRR____SSSSIIIIGGGGNNNN). If an error occurs,
the value represented by _o_v_a_l will be zero (or NNNNUUUULLLLLLLL). Note that although
some of the conversions involving the types PPPPMMMM____TTTTYYYYPPPPEEEE____SSSSTTTTRRRRIIIINNNNGGGG and
PPPPMMMM____TTTTYYYYPPPPEEEE____AAAAGGGGGGGGRRRREEEEGGGGAAAATTTTEEEE are indeed possible, but are marked N - the rationale
is that ppppmmmmEEEExxxxttttrrrraaaaccccttttVVVVaaaalllluuuueeee should not be attempting to duplicate
functionality already available in the C library via ssssssssccccaaaannnnffff(3S) and
FLOAT | P,T | P,T,S | P,T | P,T,S | Y | Y | N | N |
DBLE | P,T | P,T,S | P,T | P,T,S | P | Y | N | N |
STRING | N | N | N | N | N | N | Y | N |
AGGR | N | N | N | N | N | N | N | Y |
In the cases where multiple conversion errors could occur, the first
encountered error will be notified, and the order of checking is not
defined.
If the output conversion is to one of the pointer types, i.e. _o_t_y_p_e is
PPPPMMMM____TTTTYYYYPPPPEEEE____SSSSTTTTRRRRIIIINNNNGGGG or PPPPMMMM____TTTTYYYYPPPPEEEE____AAAAGGGGGGGGRRRREEEEGGGGAAAATTTTEEEE, then the value buffer will have been
allocated by ppppmmmmEEEExxxxttttrrrraaaaccccttttVVVVaaaalllluuuueeee(3) using mmmmaaaalllllllloooocccc(3C), and it is the caller's
responsibility to free the space when it is no longer required.
Although this function appears rather complex, it has been constructed to
assist the development of performance tools that wish to convert values,
whose type is only known via the _t_y_p_e field in a _p_m_D_e_s_c structure, into a
